Logging Subsystem Refactor — Dependency Inversion Compliance

Overview

This PR refactors the logging subsystem to resolve a Dependency Inversion Principle (DIP) violation.

Previously, the low-level moshi.moshi.utils.logging utility directly imported from the high-level moshi.moshi.client_utils module. This created an architectural violation where foundational infrastructure depended on application-layer logic, resulting in tight coupling and a fragile dependency chain.

This change introduces a clean abstraction and dependency injection to properly separate concerns and enforce layering.

Changes Summary

Architecture Separation

Introduced a LoggingProvider abstraction via a Python Protocol:

moshi/moshi/utils/logging_interface.py

The low-level utils package now defines and owns the contract for the capabilities it requires.

Decoupled Logging Utility

Refactored:

moshi/moshi/utils/logging.py

• Removed all direct imports from high-level modules
• Now operates exclusively through the LoggingProvider interface

Dependency Injection

Added a configure_logging() registration mechanism that allows high-level modules to inject their implementation into the low-level infrastructure at runtime.

Provider Implementation

Implemented ClientLoggingProvider in:

moshi/moshi/client_utils.py

This satisfies the logging contract while preserving the existing terminal colorization behavior.

Explicit Initialization

Updated application entry points:

• server.py
• offline.py

Both now explicitly wire the logging implementation during startup via:

setup_client_logging()

Technical Rationale

Dependency Inversion Principle (DIP) Compliance

• Low-level modules no longer depend on high-level modules
• Both layers depend on a shared abstraction defined in the lower layer

Circular Import Prevention

• Eliminates high → low import chains
• Reduces the risk of circular dependencies during package initialization

Zero Behavioral Regressions

• Log formats preserved
• ANSI color codes unchanged
• Handler levels unchanged

This refactor is strictly architectural with no functional behavior changes.

Verification Performed

Startup Testing

Verified:

python -m moshi.server --help

Confirmed offline.py runs correctly with the new initialization flow.

Runtime Validation

Using a bootstrap script, verified:

• ColorizedLog uses the injected provider
• Colorized output renders correctly
• Random IDs behave as expected

Isolation Check

Confirmed the logging utility can be imported independently:

import moshi.moshi.utils.logging

This no longer pulls in client_utils or its dependencies.

Files Modified

New

• moshi/moshi/utils/logging_interface.py

Updated

• moshi/moshi/utils/logging.py
• moshi/moshi/client_utils.py
• moshi/moshi/server.py
• moshi/moshi/offline.py